Authenticate a User

Users authenticate for Epicenter applications with user credentials:

• Handle - the equivalent of a username
• Password
• Group key - an optional parameter that allows the user to join a group on login

note

Technically, a user doesn't have to belong to a group. However, so many user permissions depend on group membership that it is a best practice to require group membership for a login, as in the workflow described below.

Login

To log a user in, call the authAdapter.login() function with a UserCredentials object. Note that the object must contain handle and password, but the groupKey property is optional. A successful call returns a UserSession object.

Create a session

const session = await authAdapter.login({
        handle,
        password,
        groupKey,
      });

We use the session to check group membership.

Single group

If the user is a member of a single group, the UserSession object will contain the group key in the groupKey property.

Return the session for a single-group user

if (session.groupKey) return [session] as const;

In this case, the user gets access to the simulation as a member of the group.

Multiple groups

If the user is a member of more than one group, the session object's multipleGroups property will be set to true. In this case, we ask the user to pick one of their groups before entering the simulation.

1. Get a list of the groups by calling the groupAdapter.getSessionGroups() function.
2. Redirect the user to a page where they must pick one of the groups to log in with.

Get a list of groups for the user session

const groups = await groupAdapter.getSessionGroups();

Logout

To log a user out, call the authAdapter.logout() function.

Logout

authAdapter
        .logout({
          // 401 on logout is fine, avoid propagating to errorManager.
          inert: (fault) => fault.status === 401,
        })